Tech Arsenal 1/Tech Arsenal (Arsenal Computer).ISO/tek-11/cguide.zip/CGUIDE.DOC

Text File | 1992-03-06 | 12KB | 475 lines

Nantucket Code Guidelines

The following guidelines are applicable to all source code.  Nantucket
reserves the right to alter submitted code, text, and comments if
necessary.

1    Commands and Keywords

1.1    All commands and keywords are uppercase, both in programs and
in text.  Be sure to specify the complete spelling; never use the
four-letter abbreviation:

   REPLACE CustName WITH cCustName

1.2    When specifying a command in text or in a special element other
than code, and the command includes a clause, separate each keyword
with an ellipsis (...) and do not specify the TO clause unless it is
followed by the FILE, PRINT or SCREEN keywords:

   COPY...SDF
   SET MESSAGE...CENTER
   @...SAY...GET

2    Language Syntax

2.1    When specifying the complete syntax of a language element in
text, input items, parameters, etc. are referred to using the following
symbols:

SYMBOLS

DESCRIPTION

< >
Indicates user input item

( )
Indicates function argument list

[ ]
Indicates optional item or list

{ }
Indicates code block or literal array

| |
Indicates code block argument list

-->
Indicates function return value

...
Repeated elements if followed by a symbol
Intervening code if followed by a keyword

,
List item separator

|
Indicates two or more mutually exclusive options

@
Indicates that an item must be passed by reference

*
Indicates a compatibility command or function

For example:

   LEN(<cString>|<aTarget>) --> nCount

For more examples, please consult the Clipper 5.0 Reference Guide.

2.2    Metasymbols describe the general nature of basic syntax
elements.  They are used in conjunction with the symbols listed above
to specify the syntax of a language element.  A metasymbol consists of
one or more lowercase data type designators, followed by a mixedcase
description:

   RANGE <dnLower>, <dnUpper>

In this example, dnLower and dnUpper can be either date or numeric.
Data type designators are as follows:

DESIGNATOR

DESCRIPTION

a
Array

b
Code block

c
Character expression

d
Date expression

exp
Expression of any type

id
Literal identifier

l
Logical expression

m
Memo field

n
Numeric expression

o
Object

x
Extended expression

3    Filenames

3.1    The names of Clipper program and data files have the first
letter capitalized and the extensions in lowercase (e.g., MyProg.prg,
Items.dbf).  Extensions are:

.ch
.dbt
.frm
.mem
.ntx
.prg
.dbf
.fmt
.lbl
.ndx
.txt
.vew

When referring to specific file types in text, enclose the file
extension in parentheses:

   A program is stored in a text file with a (.prg) extension.

3.2    Underscores should not be used anywhere in the filename.  Use
mixedcase for filenames consisting of more than one word:

USE CustNames

3.3    The names and extensions of other files, including executable
and DOS files, are uppercase (e.g., CLIPPER.LIB, AUTOEXEC.BAT).
Extensions are:

.ASM
.C
.CLP
.LIB
.OBJ
.PLL

.BAT
.COM
.EXE
.LNK
.OVL


When referring to specific file types in text, use the appropriate
extension, including the period:

   Clipper compiles a set of (.prg) files into one .OBJ file.

3.4    Alias names follow the same conventions as filenames.

4    Fieldnames

4.1    Capitalize the first letter of fieldnames:

   @ 10,10 SAY Branch

4.2    Do not use leading underscores: these are used for Clipper
internal variable and function names.  Underscores should not be used
anywhere in the fieldname.  Use mixedcase for fieldnames consisting of
more than one word:

   ? TotalSum, NumOfLines

4.3    Always explicitly reference fieldnames, either by using the
FIELD declaration or by preceding the fieldname with the file alias:

   FIELD CustName
   OR
   @ 10,10 SAY CustFile->CustName

@ 10,10 SAY CustName

5    Memory Variables

5.1    Memory variable names consist of a lowercase data type
designator (see section 2), followed by a mixedcase description:

   cString := "Hello world"

5.2    Underscores should not be used anywhere in a memory variable
name.  Use mixedcase for names consisting of more than one word:

   nTotalCost := Invoices->Cost

5.3    Never give memory variables the same names as database fields.

6    Functions and Procedures

6.1    Clipper function names are uppercase, followed by parentheses:

   You can create user-friendly menus with ACHOICE().

6.2    User-defined function and procedure names begin with an
uppercase letter, followed by lowercase letters as appropriate:

   ? Center("Please select a menu option", 80)

6.3    Do not use leading underscores: these are used for Clipper
internal variable and function names.  Underscores should not be used
anywhere in a function or procedure name.  Use mixedcase for names
consisting of more than one word:

   YesOrNo("Do you wish to continue?", 10, 10)

6.4    When parameters are specified as part of a function
declaration, a space is placed inside each parenthesis:

   FUNCTION SayInBox( cMessage, cColor )

6.5    The RETURN statement at the end of a function or procedure is
indented 1 tab (see example in section 15).

6.6    If a subroutine does not return a value, it should be declared
as a PROCEDURE.  A routine that returns a value should be declared as a
function.  (Note that calls to both functions and procedures can occur
in the middle of a line with arguments listed in parentheses.)

6.7    The return value of a function is enclosed in parentheses:

   RETURN (cRetValue)

6.8    Wherever possible, variables referenced by a function or
procedure should be passed as parameters.

7    Preprocessor Directives

7.1    Preprocessor directives are lowercase and are preceded by a "#"
sign:

   #include "Inkey.ch"

7.2    Pseudo-function names follow the same conventions as
user-defined function and procedure names (see section 6).

7.3    Manifest constants are uppercase:

   #define ESCAPE 27
   IF LASTKEY() == ESCAPE

7.4    A blank line should be placed before and after #if...#endif
directives:

   @ 2,10 SAY "ACME Stock Control System"

   #if PASSWORD
    <Ask user for password>
   #endif

   MainMenu()

8    Standard Classes

8.1    Class names follow the same conventions as user-defined
function and procedure names (see section 6).

8.2    Instance variable names begin with a lowercase letter, and
include uppercase letters wherever necessary to indicate new words:

   oError:canDefault := .T.

8.3    Method names follow the same convention as instance variable
names (see above):

   oBrowse:pageUp()

8.4    When referring to a class method in text, you must also specify
the class name:

   To reposition the data source to bottom-of-file, use the
   TBrowse:goBottom() method.

9    Spaces

9.1    Whenever a list of two or more items is used, a space is placed
after each comma separator:

   MyFunc(nChoice, 10, 20, .T.)

9.2    NEVER use spaces to indent code; use tabs instead (see section
15).

9.3    When parameters are specified as part of a function
declaration, a space is placed inside each parenthesis:

   FUNCTION SayInBox( cMessage, cColor )

9.4    A space is placed on either side of each binary operator:

   nTotal := nSubTotal + nNewCost

10    Declarations

10.1    Each variable is declared separately on its own line:

   LOCAL nSomeNum
   LOCAL cString := ""

11    Logicals

11.1    Logical values are referred to in text as follows:

   true (.T.)
   false (.F.)

The terms "true" and "false" are all lowercase unless they appear at
the beginning of a sentence, and are followed by the code form of the
logical value enclosed in parentheses.

12    Operators

12.1    The in-line assignment operator (:=) is used for assignments in
all Clipper 5.0 code:

   lContinue := .T.

12.2    The == operator is used for exact equality tests in all Clipper
5.0 code:

   lDuplicate := (CustFile->CustName == cCustName)

13    Tabs

13.1      Fixed tabs are at three-space intervals.  This does not mean
that a tab always expands to 3 spaces.

13.2    Tabs are always used to indent code.

13.3    When placing an in-line comment in your code, use one tab
between the end of code, and the beginning of the comment.  No other
intervening white space should exist.  (for the purpose of this
example, tabs are shown as <tab>):

   IF nTabs > 1<tab>// Only 1 tab
   <tab>.
   <tab>. <statements>
   <tab>.
   ENDIF

See also section 15 (Indentation) and 17 (Comments).

14    Missing Code

14.1    The fact that code is missing from an example is indicated by a
line containing a period, followed by a line containing a period and
"<statements>," followed by a line containing a period.  The lines are
indented as though they contained code (see section 15):

   IF nNumber == 0
    .
    . <statements>
    .
   ENDIF

15    Indentation

15.1    Tabs are used for all indentation. DO NOT uses spaces: it makes
layout extremely difficult.

15.2    Control structures and the code within functions and procedures
are indented 1 tab.  The same is true of a function or procedure's
RETURN statement.  Clipper control structures include BEGIN
SEQUENCE...END, DO CASE...ENDCASE, DO WHILE...ENDDO, EXIT, LOOP,
FOR...NEXT, and IF...ENDIF:

   PROCEDURE SaySomething
    DO WHILE .T.
        IF nTotal< 50
            ? "Less than 50"
        ELSEIF nTotal == 50
            ? "Equal to 50"
        ELSE
            ? "Greater than 50""
        ENDIF
    ENDDO
    RETURN

15.3    CASE statements in a DO CASE...ENDCASE structure are aligned
with the "DO CASE:"

   DO CASE
   CASE nChoice == 1
    .
    . <statements>
    .
   ENDCASE

15.4    Do not use abbreviations of control structures, such as WHILE
for DO WHILE and END for ENDIF or ENDDO.  Always type the entire word.

16    Line Continuation

16.1    When a line of code reaches column 60 (or at the previous
logical break), interrupt the code with a semicolon and continue on the
next line.  Indent the line by one tab to indicate a continuation:

   SET FILTER TO CustFile->Name == "Jim Bowie";
    .AND. CustFile->State == "CA"

16.2    To continue a character string, end the first line with a
quotation mark and place the remainder on the next line.  Indent the
line to indicate a continuation:

   @ 10,10 SAY "The lazy brown fox tripped over" + ;
    "the broken branch."

17    Comments

17.1    Comments begin with a capital letter, but have no period:

   // Just like a sentence, but no period

17.2    For long comments spanning several lines, use the following:

   * For Summer '87 code, put one of these at the start of each * line

   /* This type of Clipper 5.0 comment can be as large as necessary.
      Everything bound between the delimiters will be ignored by the
      preprocessor
   */

// Or you can use the double-slash (//) at the beginning of
// each line for large comments blocks.

17.3    For single-line comments, use the following // rather than *:

   // This is a single-line comment in Clipper 5.0

17.4    For in-line comments, use // rather than &&:

   USE Customer    // An in-line comment in Clipper 5.0

17.5    Do not use in-line comments for large comment blocks.  Comment
"paragraphs" should be formatted according to rule 17.2.  If an in-line
comment wraps beyond the 60th column, consider placing it above the
code on a separate line at the current indent level.

   .                   // Don't make a comment
   .<statements>       // paragraph with aligned
   .                   // in-line comments

   // Make your long in-line comments like this...
   .
   .<statements>
   .
   /* ...or, like this.  But, don't place tabs inside your
   comments. */